home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / program / progem.lzh / wind13.prf < prev    next >
Text File  |  1987-06-23  |  19KB  |  363 lines
  1. .!****************************************************************************
  2. .! 
  3. .! ANTIC PUBLISHING INC., COPYRIGHT 1985.  REPRINTED BY PERMISSION.
  4. .!
  5. .! ** Professional GEM ** by Tim Oren
  6. .!
  7. .! Proff File by ST enthusiasts at
  8. .! Case Western Reserve University
  9. .! Cleveland, Ohio
  10. .! uucp : decvax!cwruecmp!bammi
  11. .! csnet: bammi@case
  12. .! arpa : bammi%case@csnet-relay
  13. .! compuserve: 71515,155
  14. .!
  15. .!****************************************************************************
  16. .!
  17. .!
  18. .!****************************************************************************
  19. .!
  20. .!            Begin Part XIII
  21. .!
  22. .!****************************************************************************
  23. .!
  24. .PART XIII A New Form Manager
  25. .PP
  26. This  is  the 13th installment of ST PRO GEM,  and the  first
  27. devoted to explaining a large piece of code.  This article is also
  28. the  second  in a series of three concerning  GEM  user  interface
  29. techniques.   The  code is an alternate form (dialog) manager  for
  30. GEM.   It  is stored as GMCL13.C in DL3 of PCS-58.   You should go
  31. and  download it now,  or you will have no hope of following  this
  32. discussion.
  33. .PP
  34. What  is  unique  about this version  of  the  form  manager?
  35. First,  it  implements  all of the functions of the  standard  GEM
  36. form_do  routine,  as  well as adding a "hot spots" feature  which
  37. causes  selectable  objects to become mouse-sensitive,  just  like
  38. the   entries  in  menu  dropdowns.    The  second  (and  obvious)
  39. difference  is that this form manager is provided in  source  code
  40. form.   This  gives you the freedom to examine it and change it to
  41. suit your own needs.
  42. .PP
  43. I  have  several  purposes in presenting this  code.   It  is
  44. intended   as  an  example  of  GEM  program  structure,   and  an
  45. application  of  some  of  the  techniques  presented  in  earlier
  46. columns.   It is also relevant to the continuing thread discussing
  47. the necessity of feedback when constructing a user interface.
  48. .PP
  49. Also,  this  issue represents the beginning of a  fundamental
  50. change in direction for ST PRO GEM.   Since this column began last
  51. August, Atari ST developers have increased not only in number, but
  52. in sophistication.   A number of books,  as well as back issues of
  53. ST PRO GEM,  are now available to explain the basics of the ST and
  54. GEM.   Quick  answers  to common questions are available  here  on
  55. Compuserve's PCS-57 from Atari itself,  or from helpful members of
  56. the developer community.
  57. .PP
  58. To  reflect these changes,  future columns will discuss  more
  59. advanced topics in greater depth, with an accent on code which can
  60. be  adapted  by developers.   The program presented in this  issue
  61. will be a basis for a number of these discussions.   There will be
  62. fewer  "encyclopediac" treatments of AES and VDI  function  calls.
  63. Finally, to give me the time required to create this code or clean
  64. up tools from my "bag of tricks", ST PRO GEM will probably convert
  65. to a monthly format around the start of summer.
  66. .SH ON  WITH  THE SHOW
  67. Taking your listing in hand,  you  will
  68. quickly notice two things.   First, this program uses the infamous
  69. portability macros,  so that it may be used with Intel versions of
  70. GEM.  Second, the routines are arranged "bottom up", with the main
  71. at the end,  and subroutines going toward the beginning.  (This is
  72. a carry-over from my days with ALGOL and PASCAL.)  You should  now
  73. turn to the form_do entry point near the end of the code.
  74. .PP
  75. One change has been made in the standard calling sequence for
  76. m_do.   The  starting  edit field is now a pointer to a  value,
  77. rather  than  the value itself.   The new form_do  overwrites  the
  78. initial value with the number of the object being edited when  the
  79. dialog  terminated.   Using  this  information,  your program  can
  80. restore the situation when the dialog is next called.   As before,
  81. if there is NO editable field, the initial value should be zero.
  82. .PP
  83. There are several local variables which maintain vital  state
  84. information during the dialog interaction.  Edit_obj is the number
  85. of  the editable object currently receiving keystrokes.   Next_obj
  86. is  set when the mouse is clicked over an object.   If the  object
  87. happens to be editable,  next_obj becomes the new edit_obj.
  88. .PP
  89. Three  variables are associated with the "hot-spot"  feature.
  90. If hot_mode is set to M1_ENTER, then the mouse is outside the area
  91. of the dialog.   If it equals M1_EXIT, then the mouse is currently
  92. in the dialog.   If it is in the dialog, hot_obj indicates whether
  93. there is an active "hot" object.   If its value is NIL (-1),  then
  94. there is no active object.   Otherwise,  it is equal to the number
  95. of the object which is currently "hot",  that is,  inverted on the
  96. screen.   Finally, hot_rect is the current wait rectangle.  If the
  97. mouse is outside of the window, then the wait rectangle equals the
  98. dialog's  ROOT.   If there is a current hot object,  then hot_rect
  99. equals  that  object's screen rectangle.   If the mouse is in  the
  100. dialog,  but  not  within  a hot object,  then the wait  rectangle
  101. defines  the  area within which no further  collision  checks  are
  102. necessary.   This  is  arrived at through an  algorithm  explained
  103. below.
  104. .PP
  105. Form_do's initialization code sets up the hot-spot  variables
  106. to  trigger  if  the mouse is within the  dialog.   It  also  sets
  107. starting  values  for edit_obj and next_obj which will  cause  the
  108. edit startup code to be activated.
  109. .PP
  110. The main portion of form_do is a loop, exhibiting the type of
  111. event  driven  structure  discussed in the  last  column.   Before
  112. entering the evnt_multi wait,  the status of next_obj and edit_obj
  113. are  checked  to  see if a new object should  be  initialized  for
  114. editing.   If  so,  objc_edit  is called with the EDINIT  function
  115. code.   NOTE:  the objc_edit calling sequence used in this program
  116. differs from the one given in the AES manual,  which is incorrect!
  117. You  should check the bindings you are using to be sure they  will
  118. work with this code, and modify as necessary.
  119. .PP
  120. The evnt_multi is set up to wait for a mouse click (single or
  121. double),  for  a  keyboard  input,  or  for the mouse  to  make  a
  122. "significant"  movement,  as  discussed above.   Notice that since
  123. form_do is used as a subroutine, it does not handle messages which
  124. are  normally  processed  by the main loop  of  your  application.
  125. Notice that this creates a mode,  and that this routine as written
  126. handles modal dialogs.   You could,  however, use this code as the
  127. basis for a non-modal dialog handler by drawing the dialog  within
  128. a  window,  and  combining the main loop of form_do with the  main
  129. loop  of your application.   (This possibility may be examined  in
  130. future  columns.   In the meantime,  it is left as an exercise for
  131. the reader.)
  132. .PP
  133. The  event  bit vector is returned to the  variable  "which".
  134. Since events are not mutually exclusive,  each possible event type
  135. must be examined in turn before returning to the evnt_multi  call.
  136. The form manager's event handling routines are form_hot, for mouse
  137. rectangle event, form_keybd, for character input, and form_button,
  138. for  mouse  clicks.   Form_keybd  and form_button are  allowed  to
  139. terminate  the  dialog by returning a value of false to  the  loop
  140. control variable "cont".   If termination is imminent, or the user
  141. has  clicked  on a new editable object,  objc_edit is called  with
  142. EDEND  to remove the cursor from the old object.   The normal flow
  143. of control then returns to edit setup and evnt_multi.
  144. .PP
  145. A few cleanup actions are performed upon termination.  If the
  146. terminating  object  (stored in next_obj) is not the same  as  the
  147. hot_obj, then a race condition has occured and the hot object must
  148. be cleared with objc_toggle before exiting.   After this test, the
  149. final  edit_obj  value is passed back via the parameter,  and  the
  150. terminating object is returned as the function value.
  151. .SH RELAXEN UND WATCHEN DAS BLINKENLICHTE
  152. Form_hot   is
  153. responsible  for  maintaining on-screen hot-spots,  and  correctly
  154. updating  the  internal hot-spot variables.   It is about  halfway
  155. through the listing.
  156. .PP
  157. he first action in form_hot is to determine if the mouse has
  158. just exited an object which is "hot.  In this case, objc_toggle is
  159. called to unhighlight the object and reset